<!DOCTYPE html>
<html lang="en">
  <head>
    <title>SwiftSMTP  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset="utf-8">
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
    <script src="js/lunr.min.js" defer></script>
    <script src="js/typeahead.jquery.js" defer></script>
    <script src="js/jazzy.search.js" defer></script>
  </head>
  <body>


    <a title="SwiftSMTP  Reference"></a>

    <header class="header">
      <p class="header-col header-col--primary">
        <a class="header-link" href="index.html">
          SwiftSMTP Docs
        </a>
         (100% documented)
      </p>
    
      <p class="header-col--secondary">
        <form role="search" action="search.json">
          <input type="text" placeholder="Search documentation" data-typeahead>
        </form>
      </p>
    
        <p class="header-col header-col--secondary">
          <a class="header-link" href="https://github.com/IBM-Swift/Swift-SMTP/">
            <img class="header-icon" src="img/gh.png"/>
            View on GitHub
          </a>
        </p>
    
    </header>

    <p class="breadcrumbs">
      <a class="breadcrumb" href="index.html">SwiftSMTP Reference</a>
      <img class="carat" src="img/carat.png" />
      SwiftSMTP  Reference
    </p>

    <div class="content-wrapper">
      <nav class="navigation">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="Enums.html">Enumerations</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Enums/AuthMethod.html">AuthMethod</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Enums/SMTPError.html">SMTPError</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="Structs.html">Structures</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Structs/Attachment.html">Attachment</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Structs/Mail.html">Mail</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Structs/Mail/User.html">– User</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Structs/SMTP.html">SMTP</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Structs/SMTP/TLSMode.html">– TLSMode</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Structs/TLSConfiguration.html">TLSConfiguration</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="Typealiases.html">Type Aliases</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:9SwiftSMTP10Completiona">Completion</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:9SwiftSMTP8Progressa">Progress</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">

        <section class="section">
          <div class="section-content">
            
            <h1 id='swift-smtp' class='heading'>Swift-SMTP</h1>

<p><img src="https://github.com/IBM-Swift/Swift-SMTP/blob/master/Assets/swift-smtp-bird.png?raw=true" alt="Swift-SMTP bird"></p>

<p>Swift SMTP client.</p>

<p><img src="https://travis-ci.org/IBM-Swift/Swift-SMTP.svg?branch=master" alt="Build Status">
<img src="https://img.shields.io/badge/os-macOS-green.svg?style=flat" alt="macOS">
<img src="https://img.shields.io/badge/os-linux-green.svg?style=flat" alt="Linux">
<img src="https://img.shields.io/badge/license-Apache2-blue.svg?style=flat" alt="Apache 2"></p>
<h2 id='features' class='heading'>Features</h2>

<ul>
<li>Connect securely through SSL/TLS when needed</li>
<li>Authenticate with CRAM-MD5, LOGIN, PLAIN, or XOAUTH2</li>
<li>Send emails with local file, HTML, and raw data attachments</li>
<li>Add custom headers</li>
<li><a href="https://ibm-swift.github.io/Swift-SMTP/">Documentation</a></li>
</ul>
<h2 id='swift-version' class='heading'>Swift Version</h2>

<p>macOS &amp; Linux: <code>Swift 4.0.3</code> or <code>Swift 4.1</code></p>
<h2 id='migration-guide' class='heading'>Migration Guide</h2>

<p>Version <code>5.0.0</code> brings breaking changes. See the quick migration guide <a href="https://github.com/IBM-Swift/Swift-SMTP/blob/master/migration-guide.md">here</a>.</p>
<h2 id='usage' class='heading'>Usage</h2>

<p>Initialize an <code><a href="Structs/SMTP.html">SMTP</a></code> instance:</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">SwiftSMTP</span>

<span class="k">let</span> <span class="nv">smtp</span> <span class="o">=</span> <span class="kt">SMTP</span><span class="p">(</span>
    <span class="nv">hostname</span><span class="p">:</span> <span class="s">"smtp.gmail.com"</span><span class="p">,</span>     <span class="c1">// SMTP server address</span>
    <span class="nv">email</span><span class="p">:</span> <span class="s">"user@gmail.com"</span><span class="p">,</span>        <span class="c1">// username to login</span>
    <span class="nv">password</span><span class="p">:</span> <span class="s">"password"</span>            <span class="c1">// password to login</span>
<span class="p">)</span>
</code></pre>
<h3 id='tls' class='heading'>TLS</h3>

<p>Additional parameters of <code><a href="Structs/SMTP.html">SMTP</a></code> struct:</p>
<pre class="highlight swift"><code><span class="kd">public</span> <span class="nf">init</span><span class="p">(</span><span class="nv">hostname</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span>
            <span class="nv">email</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span>
            <span class="nv">password</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span>
            <span class="nv">port</span><span class="p">:</span> <span class="kt">Int32</span> <span class="o">=</span> <span class="mi">587</span><span class="p">,</span>
            <span class="nv">tlsMode</span><span class="p">:</span> <span class="kt">TLSMode</span> <span class="o">=</span> <span class="o">.</span><span class="n">requireSTARTTLS</span><span class="p">,</span>
            <span class="nv">tlsConfiguration</span><span class="p">:</span> <span class="kt">TLSConfiguration</span><span class="p">?</span> <span class="o">=</span> <span class="kc">nil</span><span class="p">,</span>
            <span class="nv">authMethods</span><span class="p">:</span> <span class="p">[</span><span class="kt">AuthMethod</span><span class="p">]</span> <span class="o">=</span> <span class="p">[],</span>
            <span class="nv">domainName</span><span class="p">:</span> <span class="kt">String</span> <span class="o">=</span> <span class="s">"localhost"</span><span class="p">,</span>
            <span class="nv">timeout</span><span class="p">:</span> <span class="kt">UInt</span> <span class="o">=</span> <span class="mi">10</span><span class="p">)</span>
</code></pre>

<p>By default, the <code><a href="Structs/SMTP.html">SMTP</a></code> struct connects on port <code>587</code> and sends mail only if a TLS connection can be established. It also uses a <code><a href="Structs/TLSConfiguration.html">TLSConfiguration</a></code> that uses no backing certificates. View the <a href="https://ibm-swift.github.io/Swift-SMTP/">docs</a> for more configuration options.</p>
<h3 id='send-email' class='heading'>Send email</h3>

<p>Create a <code><a href="Structs/Mail.html">Mail</a></code> object and use your <code><a href="Structs/SMTP.html">SMTP</a></code> handle to send it. To set the sender and receiver of an email, use the <code>User</code> struct:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">drLight</span> <span class="o">=</span> <span class="kt">Mail</span><span class="o">.</span><span class="kt">User</span><span class="p">(</span><span class="nv">name</span><span class="p">:</span> <span class="s">"Dr. Light"</span><span class="p">,</span> <span class="nv">email</span><span class="p">:</span> <span class="s">"drlight@gmail.com"</span><span class="p">)</span>
<span class="k">let</span> <span class="nv">megaman</span> <span class="o">=</span> <span class="kt">Mail</span><span class="o">.</span><span class="kt">User</span><span class="p">(</span><span class="nv">name</span><span class="p">:</span> <span class="s">"Megaman"</span><span class="p">,</span> <span class="nv">email</span><span class="p">:</span> <span class="s">"megaman@gmail.com"</span><span class="p">)</span>

<span class="k">let</span> <span class="nv">mail</span> <span class="o">=</span> <span class="kt">Mail</span><span class="p">(</span>
    <span class="nv">from</span><span class="p">:</span> <span class="n">drLight</span><span class="p">,</span>
    <span class="nv">to</span><span class="p">:</span> <span class="p">[</span><span class="n">megaman</span><span class="p">],</span>
    <span class="nv">subject</span><span class="p">:</span> <span class="s">"Humans and robots living together in harmony and equality."</span><span class="p">,</span>
    <span class="nv">text</span><span class="p">:</span> <span class="s">"That was my ultimate wish."</span>
<span class="p">)</span>

<span class="n">smtp</span><span class="o">.</span><span class="nf">send</span><span class="p">(</span><span class="n">mail</span><span class="p">)</span> <span class="p">{</span> <span class="p">(</span><span class="n">error</span><span class="p">)</span> <span class="k">in</span>
    <span class="k">if</span> <span class="k">let</span> <span class="nv">error</span> <span class="o">=</span> <span class="n">error</span> <span class="p">{</span>
        <span class="nf">print</span><span class="p">(</span><span class="n">error</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>

<p>Add Cc and Bcc:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">roll</span> <span class="o">=</span> <span class="kt">Mail</span><span class="o">.</span><span class="kt">User</span><span class="p">(</span><span class="nv">name</span><span class="p">:</span> <span class="s">"Roll"</span><span class="p">,</span> <span class="nv">email</span><span class="p">:</span> <span class="s">"roll@gmail.com"</span><span class="p">)</span>
<span class="k">let</span> <span class="nv">zero</span> <span class="o">=</span> <span class="kt">Mail</span><span class="o">.</span><span class="kt">User</span><span class="p">(</span><span class="nv">name</span><span class="p">:</span> <span class="s">"Zero"</span><span class="p">,</span> <span class="nv">email</span><span class="p">:</span> <span class="s">"zero@gmail.com"</span><span class="p">)</span>

<span class="k">let</span> <span class="nv">mail</span> <span class="o">=</span> <span class="kt">Mail</span><span class="p">(</span>
    <span class="nv">from</span><span class="p">:</span> <span class="n">drLight</span><span class="p">,</span>
    <span class="nv">to</span><span class="p">:</span> <span class="p">[</span><span class="n">megaman</span><span class="p">],</span>
    <span class="nv">cc</span><span class="p">:</span> <span class="p">[</span><span class="n">roll</span><span class="p">],</span>
    <span class="nv">bcc</span><span class="p">:</span> <span class="p">[</span><span class="n">zero</span><span class="p">],</span>
    <span class="nv">subject</span><span class="p">:</span> <span class="s">"Robots should be used for the betterment of mankind."</span><span class="p">,</span>
    <span class="nv">text</span><span class="p">:</span> <span class="s">"Any other use would be...unethical."</span>
<span class="p">)</span>

<span class="n">smtp</span><span class="o">.</span><span class="nf">send</span><span class="p">(</span><span class="n">mail</span><span class="p">)</span>
</code></pre>
<h3 id='send-attachments' class='heading'>Send attachments</h3>

<p>Create an <code><a href="Structs/Attachment.html">Attachment</a></code>, attach it to your <code><a href="Structs/Mail.html">Mail</a></code>, and send it through the <code><a href="Structs/SMTP.html">SMTP</a></code> handle. Here&rsquo;s an example of how you can send the three supported types of attachments&ndash;a local file, HTML, and raw data:</p>
<pre class="highlight swift"><code><span class="c1">// Create a file `Attachment`</span>
<span class="k">let</span> <span class="nv">fileAttachment</span> <span class="o">=</span> <span class="kt">Attachment</span><span class="p">(</span>
    <span class="nv">filePath</span><span class="p">:</span> <span class="s">"~/img.png"</span><span class="p">,</span>          
    <span class="c1">// "CONTENT-ID" lets you reference this in another attachment</span>
    <span class="nv">additionalHeaders</span><span class="p">:</span> <span class="p">[</span><span class="s">"CONTENT-ID"</span><span class="p">:</span> <span class="s">"img001"</span><span class="p">]</span>
<span class="p">)</span>

<span class="c1">// Create an HTML `Attachment`</span>
<span class="k">let</span> <span class="nv">htmlAttachment</span> <span class="o">=</span> <span class="kt">Attachment</span><span class="p">(</span>
    <span class="nv">htmlContent</span><span class="p">:</span> <span class="s">"&lt;html&gt;Here's an image: &lt;img src=</span><span class="se">\"</span><span class="s">cid:img001</span><span class="se">\"</span><span class="s">/&gt;&lt;/html&gt;"</span><span class="p">,</span>
    <span class="c1">// To reference `fileAttachment`</span>
    <span class="nv">related</span><span class="p">:</span> <span class="p">[</span><span class="n">fileAttachment</span><span class="p">]</span>
<span class="p">)</span>

<span class="c1">// Create a data `Attachment`</span>
<span class="k">let</span> <span class="nv">data</span> <span class="o">=</span> <span class="s">"{</span><span class="se">\"</span><span class="s">key</span><span class="se">\"</span><span class="s">: </span><span class="se">\"</span><span class="s">hello world</span><span class="se">\"</span><span class="s">}"</span><span class="o">.</span><span class="nf">data</span><span class="p">(</span><span class="nv">using</span><span class="p">:</span> <span class="o">.</span><span class="n">utf8</span><span class="p">)</span><span class="o">!</span>
<span class="k">let</span> <span class="nv">dataAttachment</span> <span class="o">=</span> <span class="kt">Attachment</span><span class="p">(</span>
    <span class="nv">data</span><span class="p">:</span> <span class="n">data</span><span class="p">,</span>
    <span class="nv">mime</span><span class="p">:</span> <span class="s">"application/json"</span><span class="p">,</span>
    <span class="nv">name</span><span class="p">:</span> <span class="s">"file.json"</span><span class="p">,</span>
    <span class="c1">// send as a standalone attachment</span>
    <span class="nv">inline</span><span class="p">:</span> <span class="kc">false</span>   
<span class="p">)</span>

<span class="c1">// Create a `Mail` and include the `Attachment`s</span>
<span class="k">let</span> <span class="nv">mail</span> <span class="o">=</span> <span class="kt">Mail</span><span class="p">(</span>
    <span class="nv">from</span><span class="p">:</span> <span class="n">from</span><span class="p">,</span>
    <span class="nv">to</span><span class="p">:</span> <span class="p">[</span><span class="n">to</span><span class="p">],</span>
    <span class="nv">subject</span><span class="p">:</span> <span class="s">"Check out this image and JSON file!"</span><span class="p">,</span>
    <span class="c1">// The attachments we created earlier</span>
    <span class="nv">attachments</span><span class="p">:</span> <span class="p">[</span><span class="n">htmlAttachment</span><span class="p">,</span> <span class="n">dataAttachment</span><span class="p">]</span>
<span class="p">)</span>

<span class="c1">// Send the mail</span>
<span class="n">smtp</span><span class="o">.</span><span class="nf">send</span><span class="p">(</span><span class="n">mail</span><span class="p">)</span>

<span class="cm">/* Each type of attachment has additional parameters for further customization */</span>
</code></pre>
<h3 id='send-multiple-mails' class='heading'>Send multiple mails</h3>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">mail1</span><span class="p">:</span> <span class="kt">Mail</span> <span class="o">=</span> <span class="c1">//...</span>
<span class="k">let</span> <span class="nv">mail2</span><span class="p">:</span> <span class="kt">Mail</span> <span class="o">=</span> <span class="c1">//...</span>

<span class="n">smtp</span><span class="o">.</span><span class="nf">send</span><span class="p">([</span><span class="n">mail1</span><span class="p">,</span> <span class="n">mail2</span><span class="p">],</span>
    <span class="c1">// This optional callback gets called after each `Mail` is sent.</span>
    <span class="c1">// `mail` is the attempted `Mail`, `error` is the error if one occured.</span>
    <span class="nv">progress</span><span class="p">:</span> <span class="p">{</span> <span class="p">(</span><span class="n">mail</span><span class="p">,</span> <span class="n">error</span><span class="p">)</span> <span class="k">in</span>
    <span class="p">},</span>

    <span class="c1">// This optional callback gets called after all the mails have been sent.</span>
    <span class="c1">// `sent` is an array of the successfully sent `Mail`s.</span>
    <span class="c1">// `failed` is an array of (Mail, Error)--the failed `Mail`s and their corresponding errors.</span>
    <span class="nv">completion</span><span class="p">:</span> <span class="p">{</span> <span class="p">(</span><span class="n">sent</span><span class="p">,</span> <span class="n">failed</span><span class="p">)</span> <span class="k">in</span>
    <span class="p">}</span>
<span class="p">)</span>
</code></pre>
<h2 id='acknowledgements' class='heading'>Acknowledgements</h2>

<p>Inspired by <a href="https://github.com/onevcat/Hedwig">Hedwig</a> and <a href="https://github.com/PerfectlySoft/Perfect-SMTP">Perfect-SMTP</a>.</p>
<h2 id='license' class='heading'>License</h2>

<p>Apache v2.0</p>

          </div>
        </section>


      </article>
    </div>
    <section class="footer">
      <p>&copy; 2018 <a class="link" href="" target="_blank" rel="external">IBM</a>. All rights reserved. (Last updated: 2018-06-26)</p>
      <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.9.0</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
    </section>
  </body>
</div>
</html>
